<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- qscriptengineagent.cpp -->
<head>
  <title>QScriptEngineAgent Class Reference</title>
  <link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top" width="32"><img src="images/qt-logo.png" align="left" width="57" height="67" border="0" /></td>
<td width="1">&nbsp;&nbsp;</td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a></td>
</tr></table><h1 class="title">QScriptEngineAgent Class Reference<br /><span class="small-subtitle">[<a href="http://qt.nokia.com/doc/4.6/qtscript.html">QtScript</a> module]</span>
</h1>
<p>The QScriptEngineAgent class provides an interface to report events pertaining to <a href="qscriptengine.html">QScriptEngine</a> execution. <a href="#details">More...</a></p>
<pre> #include &lt;QScriptEngineAgent&gt;</pre><p><b>This class is not part of the Qt GUI Framework Edition.</b></p>
<p>This class was introduced in qtscriptclassic 4.4.</p>
<ul>
<li><a href="qscriptengineagent-members.html">List of all members, including inherited members</a></li>
</ul>
<hr />
<a name="public-types"></a>
<h2>Public Types</h2>
<table class="alignedsummary" border="0" cellpadding="0" cellspacing="0" width="100%">
<tr><td class="memItemLeft" align="right" valign="top">enum </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#Extension-enum">Extension</a></b> { DebuggerInvocationRequest }</td></tr>
</table>
<hr />
<a name="public-functions"></a>
<h2>Public Functions</h2>
<table class="alignedsummary" border="0" cellpadding="0" cellspacing="0" width="100%">
<tr><td class="memItemLeft" align="right" valign="top"></td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#QScriptEngineAgent">QScriptEngineAgent</a></b> ( QScriptEngine * <i>engine</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#dtor.QScriptEngineAgent">~QScriptEngineAgent</a></b> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#contextPop">contextPop</a></b> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#contextPush">contextPush</a></b> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">QScriptEngine * </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#engine">engine</a></b> () const</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#exceptionCatch">exceptionCatch</a></b> ( qint64 <i>scriptId</i>, const QScriptValue &amp; <i>exception</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#exceptionThrow">exceptionThrow</a></b> ( qint64 <i>scriptId</i>, const QScriptValue &amp; <i>exception</i>, bool <i>hasHandler</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual QVariant </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#extension">extension</a></b> ( Extension <i>extension</i>, const QVariant &amp; <i>argument</i> = QVariant() )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#functionEntry">functionEntry</a></b> ( qint64 <i>scriptId</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#functionExit">functionExit</a></b> ( qint64 <i>scriptId</i>, const QScriptValue &amp; <i>returnValue</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#positionChange">positionChange</a></b> ( qint64 <i>scriptId</i>, int <i>lineNumber</i>, int <i>columnNumber</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#scriptLoad">scriptLoad</a></b> ( qint64 <i>id</i>, const QString &amp; <i>program</i>, const QString &amp; <i>fileName</i>, int <i>baseLineNumber</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#scriptUnload">scriptUnload</a></b> ( qint64 <i>id</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual bool </td><td class="memItemRight" valign="bottom"><b><a href="qscriptengineagent.html#supportsExtension">supportsExtension</a></b> ( Extension <i>extension</i> ) const</td></tr>
</table>
<a name="details"></a>
<hr />
<h2>Detailed Description</h2>
<p>The QScriptEngineAgent class provides an interface to report events pertaining to <a href="qscriptengine.html">QScriptEngine</a> execution.</p>
<p>The QScriptEngineAgent class is the basis of tools that monitor and/or control the execution of a <a href="qscriptengine.html">QScriptEngine</a>, such as debuggers and profilers.</p>
<p>To process script loading and unloading events, reimplement the <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>() and <a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>() functions. <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>() is called after the input to <a href="qscriptengine.html#evaluate">QScriptEngine::evaluate</a>() has been parsed, right before the given script is executed. The engine assigns each script an ID, which is available as one of the arguments to <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>(); subsequently, other event handlers can use the ID to identify a particular script. One common usage of <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>() is to retain the script text, filename and base line number (the original input to <a href="qscriptengine.html#evaluate">QScriptEngine::evaluate</a>()), so that other event handlers can e.g&#x2e; map a line number to the corresponding line of text.</p>
<p><a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>() is called when the <a href="qscriptengine.html">QScriptEngine</a> has no further use for a script; the QScriptEngineAgent may at this point safely discard any resources associated with the script (such as the script text). Note that after <a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>() has been called, the <a href="qscriptengine.html">QScriptEngine</a> may reuse the relevant script ID for new scripts (i.e&#x2e; as argument to a subsequent call to <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>()).</p>
<p>Evaluating the following script will result in <a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>() being called immediately after evaluation has completed:</p>
<pre> var a = Math.random() + 2;</pre>
<p>Evaluating the following script will \b{not} result in a call to <a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>() when evaluation has completed:</p>
<pre> function cube(a) {
     return a * a * a;
 }

 var a = cube(3);</pre>
<p>The script isn't unloaded because it defines a function (<tt>cube</tt>) that remains in the script environment after evaluation has completed. If a subsequent script removed the <tt>cube</tt> function (e.g&#x2e; by setting it to <tt>null</tt>), <a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>() would be called when the function is garbage collected. In general terms, a script isn't unloaded until the engine has determined that none of its contents is referenced.</p>
<p>To process script function calls and returns, reimplement the <a href="qscriptengineagent.html#functionEntry">functionEntry</a>() and <a href="qscriptengineagent.html#functionExit">functionExit</a>() functions. <a href="qscriptengineagent.html#functionEntry">functionEntry</a>() is called when a script function is about to be executed; <a href="qscriptengineagent.html#functionExit">functionExit</a>() is called when a script function is about to return, either normally or due to an exception.</p>
<p>To process individual script statements, reimplement <a href="qscriptengineagent.html#positionChange">positionChange</a>(). <a href="qscriptengineagent.html#positionChange">positionChange</a>() is called each time the engine is about to execute a new statement of a script, and thus offers the finest level of script monitoring.</p>
<p>To process exceptions, reimplement <a href="qscriptengineagent.html#exceptionThrow">exceptionThrow</a>() and <a href="qscriptengineagent.html#exceptionCatch">exceptionCatch</a>(). <a href="qscriptengineagent.html#exceptionThrow">exceptionThrow</a>() is called when a script exception is thrown, before it has been handled. <a href="qscriptengineagent.html#exceptionCatch">exceptionCatch</a>() is called when an exception handler is present, and execution is about to be resumed at the handler code.</p>
<p>See also <a href="qscriptengine.html#setAgent">QScriptEngine::setAgent</a>() and <a href="qscriptcontextinfo.html">QScriptContextInfo</a>.</p>
<hr />
<h2>Member Type Documentation</h2>
<h3 class="fn"><a name="Extension-enum"></a>enum QScriptEngineAgent::Extension</h3>
<p>This enum specifies the possible extensions to a <a href="qscriptengineagent.html">QScriptEngineAgent</a>.</p>
<p><table class="valuelist" border="1" cellpadding="2" cellspacing="1" width="100%">
<tr><th width="25%">Constant</th><th width="15%">Value</th><th width="60%">Description</th></tr>
<tr><td valign="top"><tt>QScriptEngineAgent::DebuggerInvocationRequest</tt></td><td align="center" valign="top"><tt>0</tt></td><td valign="top">The agent handles <tt>debugger</tt> script statements.</td></tr>
</table></p>
<p>See also <a href="qscriptengineagent.html#extension">extension</a>().</p>
<hr />
<h2>Member Function Documentation</h2>
<h3 class="fn"><a name="QScriptEngineAgent"></a>QScriptEngineAgent::QScriptEngineAgent ( <a href="qscriptengine.html">QScriptEngine</a> * <i>engine</i> )</h3>
<p>Constructs a <a href="qscriptengineagent.html">QScriptEngineAgent</a> object for the given <i>engine</i>.</p>
<p>The engine takes ownership of the agent.</p>
<p>Call <a href="qscriptengine.html#setAgent">QScriptEngine::setAgent</a>() to make this agent the active agent.</p>
<h3 class="fn"><a name="dtor.QScriptEngineAgent"></a>QScriptEngineAgent::~QScriptEngineAgent ()&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>Destroys this <a href="qscriptengineagent.html">QScriptEngineAgent</a>.</p>
<h3 class="fn"><a name="contextPop"></a>void QScriptEngineAgent::contextPop ()&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>This function is called when the current script context is about to be popped.</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#contextPush">contextPush</a>() and <a href="qscriptengineagent.html#functionExit">functionExit</a>().</p>
<h3 class="fn"><a name="contextPush"></a>void QScriptEngineAgent::contextPush ()&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>This function is called when a new script context has been pushed.</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#contextPop">contextPop</a>() and <a href="qscriptengineagent.html#functionEntry">functionEntry</a>().</p>
<h3 class="fn"><a name="engine"></a><a href="qscriptengine.html">QScriptEngine</a> * QScriptEngineAgent::engine () const</h3>
<p>Returns the <a href="qscriptengine.html">QScriptEngine</a> that this agent is associated with.</p>
<h3 class="fn"><a name="exceptionCatch"></a>void QScriptEngineAgent::exceptionCatch ( <a href="http://qt.nokia.com/doc/4.6/qtglobal.html#qint64-typedef">qint64</a> <i>scriptId</i>, const <a href="qscriptvalue.html">QScriptValue</a> &amp; <i>exception</i> )&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>This function is called when the given <i>exception</i> is about to be caught, in the script identified by <i>scriptId</i>.</p>
<p>Reimplement this function if you want to handle this event.</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#exceptionThrow">exceptionThrow</a>().</p>
<h3 class="fn"><a name="exceptionThrow"></a>void QScriptEngineAgent::exceptionThrow ( <a href="http://qt.nokia.com/doc/4.6/qtglobal.html#qint64-typedef">qint64</a> <i>scriptId</i>, const <a href="qscriptvalue.html">QScriptValue</a> &amp; <i>exception</i>, bool <i>hasHandler</i> )&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>This function is called when the given <i>exception</i> has occurred in the engine, in the script identified by <i>scriptId</i>. If the exception was thrown by a native Qt Script function, <i>scriptId</i> is -1.</p>
<p>If <i>hasHandler</i> is true, there is a <tt>catch</tt> or <tt>finally</tt> block that will handle the exception. If <i>hasHandler</i> is false, there is no handler for the exception.</p>
<p>Reimplement this function if you want to handle this event. For example, a debugger can notify the user when an uncaught exception occurs (i.e&#x2e; <i>hasHandler</i> is false).</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#exceptionCatch">exceptionCatch</a>().</p>
<h3 class="fn"><a name="extension"></a><a href="http://qt.nokia.com/doc/4.6/qvariant.html">QVariant</a> QScriptEngineAgent::extension ( <a href="qscriptengineagent.html#Extension-enum">Extension</a> <i>extension</i>, const <a href="http://qt.nokia.com/doc/4.6/qvariant.html">QVariant</a> &amp; <i>argument</i> = QVariant() )&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>This virtual function can be reimplemented in a <a href="qscriptengineagent.html">QScriptEngineAgent</a> subclass to provide support for extensions. The optional <i>argument</i> can be provided as input to the <i>extension</i>; the result must be returned in the form of a <a href="http://qt.nokia.com/doc/4.6/qvariant.html">QVariant</a>. You can call <a href="qscriptengineagent.html#supportsExtension">supportsExtension</a>() to check if an extension is supported by the <a href="qscriptengineagent.html">QScriptEngineAgent</a>. By default, no extensions are supported, and this function returns an invalid <a href="http://qt.nokia.com/doc/4.6/qvariant.html">QVariant</a>.</p>
<p>If you implement the <a href="qscriptengineagent.html#Extension-enum">DebuggerInvocationRequest</a> extension, Qt Script will call this function when a <tt>debugger</tt> statement is encountered in a script. The <i>argument</i> is a <a href="http://qt.nokia.com/doc/4.6/qvariant.html#QVariantList-typedef">QVariantList</a> containing three items: The first item is the scriptId (a qint64), the second item is the line number (an int), and the third item is the column number (an int).</p>
<p>See also <a href="qscriptengineagent.html#supportsExtension">supportsExtension</a>().</p>
<h3 class="fn"><a name="functionEntry"></a>void QScriptEngineAgent::functionEntry ( <a href="http://qt.nokia.com/doc/4.6/qtglobal.html#qint64-typedef">qint64</a> <i>scriptId</i> )&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>This function is called when a script function is called in the engine. If the script function is not a native Qt Script function, it resides in the script identified by <i>scriptId</i>; otherwise, <i>scriptId</i> is -1.</p>
<p>This function is called just before execution of the script function begins. You can obtain the <a href="qscriptcontext.html">QScriptContext</a> associated with the function call with <a href="qscriptengine.html#currentContext">QScriptEngine::currentContext</a>(). The arguments passed to the function are available.</p>
<p>Reimplement this function to handle this event. For example, a debugger implementation could reimplement this function (and <a href="qscriptengineagent.html#functionExit">functionExit</a>()) to keep track of the call stack and provide step-over functionality.</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#functionExit">functionExit</a>(), <a href="qscriptengineagent.html#positionChange">positionChange</a>(), and <a href="qscriptengine.html#currentContext">QScriptEngine::currentContext</a>().</p>
<h3 class="fn"><a name="functionExit"></a>void QScriptEngineAgent::functionExit ( <a href="http://qt.nokia.com/doc/4.6/qtglobal.html#qint64-typedef">qint64</a> <i>scriptId</i>, const <a href="qscriptvalue.html">QScriptValue</a> &amp; <i>returnValue</i> )&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>This function is called when the currently executing script function is about to return. If the script function is not a native Qt Script function, it resides in the script identified by <i>scriptId</i>; otherwise, <i>scriptId</i> is -1. The <i>returnValue</i> is the value that the script function will return.</p>
<p>This function is called just before the script function returns. You can still access the <a href="qscriptcontext.html">QScriptContext</a> associated with the script function call with <a href="qscriptengine.html#currentContext">QScriptEngine::currentContext</a>().</p>
<p>If the engine's <a href="qscriptengine.html#hasUncaughtException">hasUncaughtException</a>() function returns true, the script function is exiting due to an exception; otherwise, the script function is returning normally.</p>
<p>Reimplement this function to handle this event; typically you will then also want to reimplement <a href="qscriptengineagent.html#functionEntry">functionEntry</a>().</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#functionEntry">functionEntry</a>() and <a href="qscriptengine.html#hasUncaughtException">QScriptEngine::hasUncaughtException</a>().</p>
<h3 class="fn"><a name="positionChange"></a>void QScriptEngineAgent::positionChange ( <a href="http://qt.nokia.com/doc/4.6/qtglobal.html#qint64-typedef">qint64</a> <i>scriptId</i>, int <i>lineNumber</i>, int <i>columnNumber</i> )&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>This function is called when the engine is about to execute a new statement in the script identified by <i>scriptId</i>. The statement begins on the line and column specified by <i>lineNumber</i> and <i>columnNumber</i>. This event is not generated for native Qt Script functions.</p>
<p>Reimplement this function to handle this event. For example, a debugger implementation could reimplement this function to provide line-by-line stepping, and a profiler implementation could use it to count the number of times each statement is executed.</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>() and <a href="qscriptengineagent.html#functionEntry">functionEntry</a>().</p>
<h3 class="fn"><a name="scriptLoad"></a>void QScriptEngineAgent::scriptLoad ( <a href="http://qt.nokia.com/doc/4.6/qtglobal.html#qint64-typedef">qint64</a> <i>id</i>, const <a href="http://qt.nokia.com/doc/4.6/qstring.html">QString</a> &amp; <i>program</i>, const <a href="http://qt.nokia.com/doc/4.6/qstring.html">QString</a> &amp; <i>fileName</i>, int <i>baseLineNumber</i> )&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>This function is called when the engine has parsed a script and has associated it with the given <i>id</i>. The id can be used to identify this particular script in subsequent event notifications.</p>
<p><i>program</i>, <i>fileName</i> and <i>baseLineNumber</i> are the original arguments to the <a href="qscriptengine.html#evaluate">QScriptEngine::evaluate</a>() call that triggered this event.</p>
<p>This function is called just before the script is about to be evaluated.</p>
<p>You can reimplement this function to record information about the script; for example, by retaining the script text, you can obtain the line of text corresponding to a line number in a subsequent call to <a href="qscriptengineagent.html#positionChange">positionChange</a>().</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#scriptUnload">scriptUnload</a>().</p>
<h3 class="fn"><a name="scriptUnload"></a>void QScriptEngineAgent::scriptUnload ( <a href="http://qt.nokia.com/doc/4.6/qtglobal.html#qint64-typedef">qint64</a> <i>id</i> )&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>This function is called when the engine has discarded the script identified by the given <i>id</i>.</p>
<p>You can reimplement this function to clean up any resources you have associated with the script.</p>
<p>The default implementation does nothing.</p>
<p>See also <a href="qscriptengineagent.html#scriptLoad">scriptLoad</a>().</p>
<h3 class="fn"><a name="supportsExtension"></a>bool QScriptEngineAgent::supportsExtension ( <a href="qscriptengineagent.html#Extension-enum">Extension</a> <i>extension</i> ) const&nbsp;&nbsp;<tt> [virtual]</tt></h3>
<p>Returns true if the <a href="qscriptengineagent.html">QScriptEngineAgent</a> supports the given <i>extension</i>; otherwise, false is returned. By default, no extensions are supported.</p>
<p>See also <a href="qscriptengineagent.html#extension">extension</a>().</p>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%" align="left">Copyright &copy; 2010 Nokia Corporation and/or its subsidiary(-ies)</td>
<td width="40%" align="center"><a href="http://qt.nokia.com/doc/trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt Solutions</div></td>
</tr></table></div></address></body>
</html>
